home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 24 / Amiga Format AFCD24 (Feb 1998, Issue 108).iso / -seriously_amiga- / shareware / programming / c / vbcc / doc / interface.doc < prev    next >
Text File  |  1998-01-05  |  29KB  |  810 lines
  1. (c) in 1995-97 by Volker Barthelmann
  2.  
  3. This document is under construction!
  4.  
  5. This document describes some of the internals of vbcc and tries to explain
  6. what has to be done to write a code generator for vbcc.
  7. However if someone wants to write one, I suggest to contact me first,
  8. so that it can be integrated into the source tree.
  9.  
  10. You have to create a new directory for the new target named
  11. machines/<target-name> and write the files machine.c, machine.h
  12. and machine.dt. The compiler for this target will be called
  13. vbcc<target-name> and can be built by the statement 
  14. "make TARGET=<target-name> bin/vbcc<target-name>".
  15.  
  16. From now on integer means any of {char, short, int, long} or their
  17. unsigned couterparts. Arithmetic means integer or float or double.
  18. Elementary type means arithmetic or pointer.
  19. If you intend to write a code generator for a machine with multiple
  20. different kinds of pointers you might have some problems.
  21.  
  22.  
  23. THE INTERMEDIATE CODE
  24.  
  25. vbcc will generate intermediate code for every function and pass this code
  26. to the code generator which has to convert it into the desired output.
  27.  
  28. In the future there may be a code generator generator which reads a machine
  29. description file and generates a code generator from that, but it is not
  30. clear whether this could simplify much without taking penalties in the
  31. generated code.
  32. Anyway this would be a layer on top of the current interface to the code
  33. generator so that the interface described in this document would still be
  34. valid and accessable.
  35.  
  36. The intermediate code is represented as a doubly linked list of quadruples
  37. (I am calling them ICs from now on) consisting mainly of an operator, two
  38. source operands and a target. They are represented like this:
  39.  
  40. struct IC{
  41.     struct IC *prev;
  42.     struct IC *next;
  43.     int code;
  44.     int typf;
  45.     [...]
  46.     struct obj q1;
  47.     struct obj q2;
  48.     struct obj z;
  49.     [...]
  50. };
  51.  
  52. The only members relevant to the code generator are 'prev', 'next', 'code',
  53. 'typf', 'q1', 'q2' and 'z'.
  54.  
  55. 'prev' and 'next' are pointers to the previous and next IC.
  56. The first IC has 'prev'==0 and the last one has 'next'==0.
  57.  
  58. 'typf' is the type of the operands of this IC. This can be one of:
  59.  
  60.     #define CHAR 1
  61.     #define SHORT 2
  62.     #define INT 3
  63.     #define LONG 4
  64.     #define FLOAT 5
  65.     #define DOUBLE 6
  66.     #define VOID 7
  67.     #define POINTER 8
  68.     #define ARRAY 9
  69.     #define STRUCT 10
  70.     #define UNION 11
  71.     #define ENUM 12         /*  not relevant for code generator     */
  72.     #define FUNKT 13
  73.  
  74.     and can be additionally or'ed by
  75.  
  76.     #define UNSIGNED 16
  77.     #define CONST 64
  78.     #define VOLATILE 128
  79.     #define UNCOMPLETE 256
  80.  
  81.     However only UNSIGNED is of real importance for the code generator.
  82.     'typf'&NQ yields the type without any qualifiers, 'typf'&NU yields
  83.     the type without any qualifiers but UNSIGNED.
  84.  
  85. 'q1', 'q2' and 'z' are the source1 (quelle1 in German), source2 and target
  86. (ziel).
  87. If a result has to be computed, it always will be stored in the object 'z'
  88. and the objects 'q1' and 'q2' usually may not be destroyed during this 
  89. operation.
  90.  
  91. The objects are described by this structure.
  92.  
  93. struct obj{
  94.     int flags;
  95.     int reg;
  96.     struct Var *v;
  97.     struct AddressingMode *am;
  98.     union atyps{
  99.         zchar vchar;
  100.         zchar vuchar;
  101.         zshort vshort;
  102.         zushort vushort;
  103.         zint vint;
  104.         zuint vuint;
  105.         zlong vlong;
  106.         zulong vulong;
  107.         zfloat vfloat;
  108.         zdouble vdouble;
  109.         zpointer vpointer;
  110.     }val;
  111. };
  112.  
  113. 'flags' describes what kind the object is. It can be a combination of
  114.  
  115. #define VAR 1
  116.  
  117.     The object is a variable. The pointer to its struct Var is in 'v'.
  118.     'val.vlong' vontains an offset that has to be added to it.
  119.  
  120.     A struct Var looks like:
  121.  
  122.     struct Var{
  123.         int storage_class;
  124.         [...]
  125.         char *identifier;
  126.         [...]
  127.         zlong offset;
  128.         [...]
  129.     };
  130.  
  131.     The relevant entries are:
  132.  
  133.     'identifier':
  134.  
  135.         The name of the variable. Usually only of interest for variables
  136.         with external-linkage.
  137.  
  138.     'storage_class':
  139.  
  140.         One of:
  141.             #define AUTO 1
  142.             #define REGISTER 2
  143.             #define STATIC 3
  144.             #define EXTERN  4
  145.             #define TYPEDEF 5       /*  not relevant    */
  146.  
  147.         If the variable is not assigned to a register (i.e. bit REG
  148.         is not set in the flags of the corresponding struct obj) then 
  149.         the variable can be addressed in the following ways (with 
  150.         examples of 68k-code):
  151.  
  152.         'storage_class' == AUTO or 'storage_class' == REGISTER:
  153.  
  154.             'offset' contains the offset inside the local-variables section.
  155.             The code generator must decide how it's going to handle the
  156.             activation record.
  157.             If 'offset' < 0 then the variable is a function argument on the
  158.             stack. In this case the offset in the parameter-area is
  159.              - ('offset' + 'maxalign').
  160.  
  161.             The code generator may have to calculate the actual offset
  162.             to a stack- or frame-pointer from the value in 'offset'.
  163.  
  164.                 'offset'+'val.vlong'(sp)
  165.  
  166.             Note that 'storage_class' REGISTER is equivalent to AUTO - whether
  167.             the variable is actually assigned a register is specified by
  168.             the bit REG in the 'flags' of the 'struct obj'.
  169.  
  170.         'storage_class' == EXTERN
  171.  
  172.             The variable can be addressed through its name in 'identifier'.
  173.  
  174.                 'val.vlong'+_'identifier'
  175.  
  176.         'storage_class' == STATIC
  177.  
  178.             The variable can be addressed through a numbered label. The
  179.             label number is stored in 'offset'.
  180.  
  181.                 'val.vlong'+l'offset'
  182.  
  183. #define KONST 2
  184.  
  185.     The object is a constant. Its value is in the corresponding (to 'typf')
  186.     member of 'val'.
  187.  
  188. #define DREFOBJ 32
  189.  
  190.     The content of the location in memory the object points to is used.
  191.  
  192. #define REG 64
  193.  
  194.     The object is a register. 'reg' contains its number.
  195.  
  196. #define VARADR 128
  197.  
  198.     The address of the object is to be used. Only together with static
  199.     variables (i.e. 'storage_class' STATIC or EXTERN).
  200.  
  201. The possible combinations of these flags should be:
  202.  
  203.     0 (no object)
  204.     KONST
  205.     REG
  206.     VAR
  207.     VAR|REG
  208.     REG|DREFOBJ
  209.     VAR|DREFOBJ
  210.     VAR|REG|DREFOBJ
  211.     VAR|VARADR
  212.     
  213. Also some other bits which are not relevant to the code generator may be set.
  214.  
  215. Constants will usually be in 'q2' if possible. One of the sources always is
  216. not constant and the target is always an lvalue.
  217. Unless otherwise specified all operands of an IC are of the type 'typf' 
  218. (which may be further restricted by 'code'). However not all objects have 
  219. to be used.
  220. This depends on 'code' and is listed below. In most cases (i.e. when not
  221. explicitly stated) 'typf' is an elementary type (i.e. arithmetic or pointer).
  222.  
  223. 'am' can be used to store information on special addressing modes.
  224. This has to be handled by the by the code generator. However 'am' has to be 0
  225. or has to point to a struct AddressingMode that was allocated using malloc()
  226. when the code generator returns.
  227.  
  228. 'val' stores either the value of the object if it is a constant or an offset
  229. if it is a variable.
  230.  
  231. 'code' describes the operation and can be one of:
  232.  
  233. #define ASSIGN 2
  234.  
  235.     Copy 'q1' to 'z'. 'q2.val.vlong' contains the size of the objects (this is
  236.     necessary if it is an array or a struct). 'typf' does not have to be an
  237.     elementary type!
  238.  
  239.     The only case where 'typf' == ARRAY should be in automatic initializations.
  240.  
  241.     It is also possible that ('typf'&NQ) == CHAR but the size is != 1. This is
  242.     created for an inline memcpy/strcpy where the type is not known.
  243.  
  244. #define OR 16
  245. #define XOR 17
  246. #define AND 18
  247.  
  248.     Bitwise boolean operations. q1,q2->z.
  249.     All operands are integers.
  250.  
  251. #define LSHIFT 25
  252. #define RSHIFT 26
  253.  
  254.     Bit shifting. q1,q2->z. 'q2' is the number of shifts.
  255.     All operands are integers. 
  256.  
  257. #define ADD 27
  258. #define SUB 28
  259. #define MULT 29
  260. #define DIV 30
  261.  
  262.     Standard arithmetic operations. q1,q2->z.
  263.     All operands are of arithmetic types (integers or floating point).
  264.  
  265. #define MOD 31
  266.  
  267.     Modulo (%). q1,q2->z.
  268.     All operands are integers.
  269.  
  270. #define KOMPLEMENT 33
  271.  
  272.     Bitwise complement. q1->z.
  273.     All operands are integers.
  274.  
  275. #define MINUS 38
  276.  
  277.     Unary minus. q1->z.
  278.     All operands are of arithmetic types (integers or floating point).
  279.  
  280. #define ADDRESS 40
  281.  
  282.     Get the address of an object. q1->z.
  283.     'z' is always a pointer and 'q1' is always an auto variable.
  284.  
  285. #define CALL 42
  286.  
  287.     Call the function 'q1'. Currently 'q1' is a function rather than a pointer
  288.     to a function. This may change in the future.
  289.  
  290.     'q2.val.vlong' contains the number of bytes pushed on the stack as
  291.     function arguments for this call. Those may have to be popped from the 
  292.     stack after the function returns depending on the calling mechanism.
  293.  
  294. #define CONVCHAR 50
  295. #define CONVSHORT 51
  296. #define CONVINT 52
  297. #define CONVLONG 53
  298. #define CONVFLOAT 54
  299. #define CONVDOUBLE 55
  300. #define CONVPOINTER 57
  301. #define CONVUCHAR 58
  302. #define CONVUSHORT 59
  303. #define CONVUINT 60
  304. #define CONVULONG 61
  305.  
  306.     Convert one type to another. q1->z.
  307.     'z' is always of the type 'typf'. 'q1' is a short in CONVSHORT and an
  308.     unsigned long in CONVULONG etc.
  309.     Conversions floating point<->pointers do not occur.
  310.  
  311. #define ALLOCREG 65
  312.  
  313.     From now on the register 'q1.reg' is in use. No code has to be generated
  314.     for this, but it is probably necessary to keep track of the registers
  315.     in use to know which registers are available for the code generator
  316.     at a time and which registers the function trashes.
  317.  
  318. #define FREEREG 66
  319.  
  320.     From now on the register 'q1.reg' is free.
  321.     Also it means that the value currently stored in 'q1.reg' is not used any
  322.     more and therefore provides a little bit of data flow information.
  323.     Note however that if a FREEREG follows a branch the value of the register
  324.     may be used at the target of the branch.
  325.  
  326. #define COMPARE 77
  327.  
  328.     Compare and set condition codes. q1,q2(->z).
  329.     Compare the operands and set the condition code, so that
  330.     BEQ, BNE, BLT, BGE, BLE or BGT works.
  331.     If 'z.flags' == 0 then the condition codes will be evaluated immediately
  332.     after the COMPARE, i.e. the next instruction (except possible FREEREGs)
  333.     will be a conditional branch.
  334.     However if a target supports several condition code registers and sets
  335.     the global variable 'multiple_ccs' to 1 vbcc might use those registers
  336.     and perform certain optimizations. Then 'z' may be non-empty and the
  337.     condition codes have to be stored in 'z'.
  338.  
  339. #define TEST 68
  340.  
  341.     Test 'q1' to 0 and set condition codes. q1.
  342.     This is equal to COMPARE 'q1',(corresponding constant 0)
  343.     but only the condition code for BEQ and BNE has to be set.
  344.  
  345. #define LABEL 69
  346.  
  347.     Generate a label. 'typf' specifies the number of the label.
  348.  
  349. #define BEQ 70
  350. #define BNE 71
  351. #define BLT 72
  352. #define BGE 73
  353. #define BLE 74
  354. #define BGT 75
  355.  
  356.     Branch on condition codes. (q1)
  357.     'typf' specifies the label where program execution shall continue, if the
  358.     condition code is true (otherwise continue with next statement).
  359.     The condition codes mean equal, not equal, less than, greater or equal,
  360.     less or equal and greater than.
  361.     If 'q1' is empty (q1.flags==0) then the codes set by the last COMPARE 
  362.     or TEST must be evaluated. Otherwise 'q1' contains the condition codes.
  363.  
  364.     On some machines the type of operands of a comparison (e.g unsigned or
  365.     signed) is encoded in the branch instructions rather than in the
  366.     comparison instructions. In this case the code generator has to keep
  367.     track of the type of the last comparison.
  368.  
  369. #define BRA 76
  370.  
  371.     Branch always. 'typf' specifies the label where program execution
  372.     continues.
  373.  
  374. #define PUSH 78
  375.  
  376.     Push q1 on the stack. q1.
  377.     'q2.val.vlong' contains the size of the object and 'q1' does not have to
  378.     be an elementary type (see ASSIGN).
  379.     This is only used for passing function arguments.
  380.  
  381. #define ADDI2P 81
  382.  
  383.     Add an integer to a pointer. q1,q2->z.
  384.     'q1' and 'z' are always pointers and 'q2' is an integer of type 'typf'.
  385.     'z' has to be 'q1' increased by 'q2' bytes.
  386.  
  387. #define SUBIFP 82
  388.  
  389.     Subtract an Integer from a pointer. q1,q2->z.
  390.     'q1' and 'z' are always pointers and 'q2' is an integer of type 'typf'.
  391.     'z' has to be 'q1' decreased by 'q2' bytes.
  392.  
  393. #define SUBPFP 83
  394.  
  395.     Subtract a pointer from a pointer. q1,q2->z.
  396.     'q1' and 'q2' is a pointer and 'z' is an integer of type 'typf'.
  397.     'z' has to be 'q1' - 'q2' in bytes.
  398.  
  399. #define GETRETURN 93
  400.  
  401.     Get the return value of the last function call. ->z.
  402.     If the return value is in a register this will be in 'q1.reg'. Otherwise
  403.     'q1.reg' will be 0.
  404.     This follows immediately after a CALL instruction (except possible
  405.     FREEREGs).
  406.  
  407. #define SETRETURN 94
  408.  
  409.     Set the return value of the current function. q1.
  410.     If the return value is in a register this will be in 'z.reg'. Otherwise
  411.     'z.reg' will be 0.
  412.     This is immediately followed by a function exit (i.e. it is the last
  413.     IC or followed by an unconditional branch to a label which is the last
  414.     IC - always ignoring FREEREGs).
  415.  
  416. #define MOVEFROMREG 95
  417.  
  418.     Move a register to memory. q1->z.
  419.     'q1' is always a register and 'z' an array of size 'regsize[q1.reg]'.
  420.  
  421. #define MOVETOREG 96
  422.  
  423.     Load a register from memory. q1->z.
  424.     'z' is always a register and 'q1' an array of size 'regsize[z.reg]'.
  425.  
  426. #define NOP 97
  427.  
  428.     Do nothing.
  429.  
  430.  
  431.  
  432. TARGET DATA TYPES
  433.  
  434. As the compiler should be portable we must not assume anything about
  435. the data types of the host system which is not guaranteed by
  436. ANSI/ISO C. Especially do not assume that the data types of the host
  437. system correspond to the ones of the target system.
  438.  
  439. Therefore vbcc will provide typedefs which can hold a data type
  440. of the target machine and (as there is no operator overloading in C)
  441. functions to perform arithmetic on these types.
  442.  
  443. The typedefs for the target's data types are:
  444.  
  445.     zchar           type char on the target machine
  446.     zuchar          type unsigned char on the target machine
  447.     zshort          ...
  448.     zushort
  449.     zint
  450.     zuint
  451.     zlong
  452.     zulong
  453.     zfloat
  454.     zdouble
  455.     zpointer        a byte pointer on the target machine
  456.  
  457. These typedefs and arithmetic functions to work on them will be 
  458. generated by the program dtgen when compiling vbcc.
  459. It will create the files machines/$(TARGET)/dt.h and dt.c.
  460.  
  461. These files are generated from the file machines/$(TARGET)/machine.dt 
  462. which must describe what representations the code generator needs.
  463. dtgen will then ask for available types on the host system and
  464. choose appropriate ones and/or install emulation functions if available.
  465.  
  466. machine.dt must look as follows:
  467.  
  468. Every data type representation gets a symbol (the ones which are
  469. already available can be looked up in datatypes/datatypes.h - new
  470. ones will be added when necessary).
  471. The first 11 lines now must contain the representations for the
  472. following types:
  473.  
  474. line    type
  475.  1     signed char
  476.  2     unsigned char
  477.  3     signed short
  478.  4     unsigned short
  479.  5     signed int
  480.  6     unsigned int
  481.  7     signed long
  482.  8     unsigned long
  483.  9     float
  484. 10     double
  485. 11     void *
  486.  
  487. If the code generator can use several representations these can be
  488. added on the same line separated by spaces. E.g. the code generator 
  489. for m68k does not care if the integers are stored big-endian or 
  490. little-endian on the host system because it only accesses them through
  491. the provided arithmetic functions. It does, however, access floats
  492. and doubles through byte-pointers and therefore requires them to
  493. be stored in big-endian-format.
  494.  
  495. TARGET ARITHMETIC
  496.  
  497. Now you have a lot of functions/macros performing operations using the
  498. target machine's arithmetic. You can look them up in dt.h/dt.c.
  499. E.g. zladd() takes two zlongs and returns their sum as zlong. zuladd() does
  500. the same with zulongs, zdadd() with doubles. No functions for smaller types
  501. are needed because you can calculate with the wider types and convert the
  502. results down if needed.
  503.  
  504. Also there are conversion functions which convert between types of the
  505. target machine. E.g. zl2zc takes a zlong and returns the value converted 
  506. to a zchar.
  507. Again look at dt.h/dt.c to see which ones are there.
  508.  
  509. A few functions for converting between target and host types are also
  510. there, e.g. l2zl takes a long and returns it converted to a zlong.
  511.  
  512. At last there are functions for comparing target data types. E.g. 
  513. zlleq(a,b) returns true if zlong a <= zlong b and false otherwise. 
  514. zleqto(a,b) returns true if zlong a == zlong b and false otherwise.
  515.  
  516. ADDRESSING-MODES
  517.  
  518. The intermediate code generated by vbcc does not use any 
  519. addressing-modes a target might offer. Therefore the code generator
  520. must find a way to combine several statements if it wants to make use 
  521. of these modes. E.g. on the m68k the intermediate code
  522.  
  523.     add    int    #20,a0->a1
  524.     move    int    #10->(a1)
  525.     freereg        a1
  526.  
  527. could be translated to 
  528.  
  529.     move.l    #10,20(a0)
  530.  
  531. (notice the freereg which is important).
  532.  
  533. To aid in this there is a pointer to a struct AdressingMode in every
  534. struct obj. A code generator could e.g. do a pass over the intermediate
  535. code, find possible uses for addressing-modes, allocate a struct
  536. AddressingMode and store a pointer in the struct obj effectively
  537. replacing the obj.
  538.  
  539. If the code generator supports extended addressing-modes you have to think
  540. of a way to represent them and define the structure AddressingMode so that
  541. all Modes can be stored in it. The machine independant part of vbcc will
  542. not use these modes, so your code generator has to find a way to combine
  543. several statements to make use of these modes.
  544.  
  545. When the code generator is done that pointer in every struct obj must
  546. either be zero or point to a malloc'ed struct AddressingMode which
  547. will be free'd by vbcc.
  548.  
  549. MACHINE.H
  550.  
  551. The first statement should be #include "dt.h".
  552.  
  553. #define MAXR to the number of available registers.
  554.  
  555. #define MAXGF to the number of command line flags that can be used to
  556. configure the behaviour of the code generator. This must be at least one
  557. even if you do not use any flags.
  558.  
  559. #define USEQ2ASZ as 0 or 1; if it is set to 0, no ICs where 'q2' == 'z'
  560. will be generated. This is because those ICs might be hard to implement
  561. efficiently on certain CPUs.
  562.  
  563. #define MINADDI2P to the smallest integer type (i.e. CHAR, SHORT or INT)
  564. that can be added to a pointer. Smaller types will be automatically converted
  565. to MINADDI2P when they are to be added to a pointer.
  566. This may be subsumed by shortcut() in the future.
  567.  
  568. #define BIGENDIAN as 1 if integers are represented in big endian, i.e. the
  569. most significant byte is at the lowest memory address, the least significant
  570. byte at the highest.
  571.  
  572. #define LITTLEENDIAN as 1 if integers are represented in little endian, i.e.
  573. the least significant byte is at the lowest memory address, the most
  574. significant byte at the highest.
  575.  
  576. #define SWITCHSUBS as 1 if switch-statements should be compiled into a
  577. series of SUB/TEST/BEQ instructions rather than COMPARE/BEQ. This may be
  578. useful if the target has a more efficient SUB-instruction (e.g. 68k).
  579.  
  580. #define INLINEMEMCPY to the largest size in bytes allowed for inline memcpy.
  581. Calls to memcpy/strcpy with a known size smaller than INLINEMEMCPY may be
  582. replaced by a single ASSIGN IC by vbcc.
  583. This may be replaced by a variable of type zlong in the future.
  584.  
  585. #define ORDERED_PUSH to 1 if you want PUSH-ICs for function arguments to 
  586. be generated from left to right instead right to left. 
  587.  
  588. #define HAVE_REGPARMS to 1 if the default function-call-mechanism
  589. uses register parameters. If you use this you also have to define a
  590.  
  591.     struct reg_handle {...}
  592.  
  593. This is used by the compiler to find out which register it should pass
  594. arguments in it. In machine.c you have to define an initialized
  595. variable
  596.  
  597.     struct reg_handle empty_reg_handle;
  598.  
  599. which represents the default state and a function
  600.  
  601.     int reg_parm(struct reg_handle *, struct Typ *);
  602.  
  603. which returns the number of the register the next argument will be
  604. passed in (or 0 if the argument is not passed in a register) and
  605. updates the reg_handle in a way that successive calls to reg_parm()
  606. yield the correct register for every argument.
  607.  
  608.  
  609. MACHINE.C
  610.  
  611. This is the main part of the code generator. The first statement
  612. should be #include "supp.h" which will include all necessary
  613. declarations.
  614.  
  615. The following variables and functions must be provided by machine.c.
  616.  
  617. NAME AND COPYRIGHT
  618.  
  619.     The codegenerater must define a zero-terminated character array
  620.     containing name and copyright-notice of the code-generator.
  621.  
  622. COMMANDLINE OPTIONS
  623.  
  624.     You can use code generator specific commandline options.
  625.     The number of flags is specified as MAXGF in machine.h.
  626.     Insert the names for the flags as char *g_flags_name[MAXGF].
  627.     If an option was specified (g_flags[i]&USEDFLAG) is not zero.
  628.     In int g_flags[MAXGF] you can also choose how the options are to be
  629.     used:
  630.         0       The option can only be specified. E.g. if
  631.                 g_flags_name[2]=="myflag", the commandline may contain
  632.                 "-myflag" and (g_flags[2]&USEDFLAG)!=0.
  633.       VALFLAG   The option must be specified with an integer constant, e.g.
  634.                 "-myflag=1234". This value can be found in g_flags_val[2].l
  635.                 then.
  636.     STRINGFLAG  The option must be specified with a string, e.g.
  637.                 "-myflag=Hallo". The pointer to the string can be found in
  638.                 g_flags_val[2].p then.
  639.  
  640. DATA TYPES
  641.  
  642.     The array zlong align[16] must contain the necessary alignments for every
  643.     type in bytes. Some of the entries in this array are not actually
  644.     used, but align[type&15] must yield the correct alignment for every type.
  645.     align[CHAR] must be 1.
  646.  
  647.     zlong maxalign; must be set to an alignment in bytes that is used when
  648.     pushing arguments on the stack.
  649.  
  650.     The array zlong sizetab[16] must contain the sizes of every type in bytes.
  651.  
  652.     The array zlong t_min[32] must contain the smallest number for every
  653.     integer type (including unsigned ones).
  654.     The array zulong t_max[32] must contain the greatest number for every
  655.     integer type (including unsigned ones).
  656.  
  657.     As zlong and zulong may be no elementary types on the host machine those
  658.     arrays have to be initialized dynamically.
  659.     Also note that if you want the code generator to be portable those values
  660.     may not be representable as constants by the host architecture and have to
  661.     be calculated using the functions for arithmetic on the target's data
  662.     types. E.g. the smallest representable value of a 32bit twos-complement
  663.     data type is not guaranteed to be valid on every ANSI C implementation.
  664.  
  665.     Also note that you may not use simple operators on the target data types
  666.     but you have to use the functions or convert them to an elementary
  667.     type of the host machine before (if you know that it is representable
  668.     as such).
  669.  
  670. REGISTER SET
  671.  
  672.     The valid registers are numbered from 1..MAXR.
  673.  
  674.     The array char *regnames[MAXR+1] must contain the names for every register.
  675.  
  676.     zlong regsize[MAXR+1] must contain the size of each register in bytes.
  677.     This is used to create storage if registers have to be saved.
  678.  
  679.     int regscratch[MAXR+1] must contain information whether a register is
  680.     a scratchregister i.e. may be destroyed during a function call (1 or 0).
  681.     vbcc will generate code to save/restore all scratch-registers which are
  682.     assigned a value when calling a function. However if the code generator
  683.     uses additional scratch-registers it has to take care to save/restore
  684.     them.
  685.     Also the code generator must save/restore used non-scratch-registers
  686.     on function entry/exit.
  687.  
  688.     int regsa[MAXR+1] must contain information whether a register is in use
  689.     or not at the beginning of a function (1 or 0).
  690.     The compiler will not use any of those registers for register variables
  691.     or temporaries.
  692.     You _must_ set regsratch[i] = 0 if regsa[i] == 1. If you want it to be
  693.     save across function calls the code generator has to take care of this.
  694.  
  695.     You should order the registers so that the ones that should be used 
  696.     first have the smallest number and it is recommended that registers 
  697.     which are used to pass return values be assigned the lowest numbers.
  698.  
  699.     Also you may reserve certain registers to the code generator. This may 
  700.     be reasonable if many ICs cannot be converted without using additional
  701.     registers.
  702.  
  703. FUNCTIONS
  704.  
  705. The following functions have to be implemented by the code generator:
  706.  
  707. - int init_cg(void);
  708.  
  709.     This function is called after the commandline arguments are parsed.
  710.     It can set up certain internal data, etc. The arrays regarding the
  711.     data types and the register set, can be set up at this point rather
  712.     than with a static initialization, however the arrays regarding the
  713.     commandline options have to be static initialized.
  714.     The results of the commandline options are available at this point.
  715.  
  716.     If something goes wrong, 0 has to be returned, otherwise 1.
  717.  
  718. - void cleanup_cg(FILE *f)
  719.  
  720.     This function is called before the compiler exits. f is the output file
  721.     which _must_ be checked against 0 before using.
  722.  
  723. - int freturn(struct Typ *t);
  724.  
  725.     This function has to return the number of the register return
  726.     values of type t are passed in. If the type is not passed in a
  727.     register, 0 must be returned.
  728.  
  729. - int regok(int r, int t, int mode);
  730.  
  731.     Check whether the type t can be stored in register r; return 0, if not.
  732.     If t==POINTER and mode==0 the register only has to be able to store the
  733.     pointer, but if mode!=0 it has to be able to dereference the pointer.
  734.  
  735.     If t==0 return whether the register can be used to store condition codes.
  736.     This is only relevant if multiple_ccs is set to 1.
  737.  
  738. - int dangerous_IC(struct IC *p)
  739.  
  740.     Check if this IC can raise exceptions or is otherwise dangerous.
  741.     Movement of ICs which are dangerous is restricted to preserve the
  742.     semantics of the program.
  743.     Typical dangerous ICs are divisions or pointer dereferencing. On certain
  744.     targets floating point or even signed integer arithmetic can raise
  745.     exceptions, too.
  746.  
  747. - int must_convert(np p, int t)
  748.  
  749.     Check if type in p does not have to be converted to type t. E.g. on
  750.     many machines certain types have identical representations (integers
  751.     of the same size or pointers and integers of the same size).
  752.     WARNING: Arguments of this functions may change in the future!
  753.  
  754. - int shortcut(int code, int t)
  755.  
  756.     In C no operations are done with chars and shorts because of integral
  757.     promotion. However sometimes vbcc might see that an operation could
  758.     be performed with the short types yielding the same result.
  759.  
  760.     Before generating such an instruction with short types vbcc will ask
  761.     the code generator by calling shortcut() to find out whether it should
  762.     do so. Return true iff it is a win to perform the operation code with
  763.     type t rather than promoting the operands and using int or so.
  764.  
  765. - void gen_code(FILE *f, struct IC *p, struct Var *v, zlong offset);
  766.  
  767.     This function has to generate the output for a function to stream f.
  768.     v is a pointer to the function which contains the name of the function.
  769.     p is a pointer to the first IC, that has to be converted.
  770.     offset is the space needed for local variables in bytes.
  771.  
  772.     This function has to take care that only scratchregisters are destroyed
  773.     by this function. The array regused contains information about the
  774.     registers that have been used by vbcc in this function. However if the
  775.     code generator uses additional registers it has to take care of them,
  776.     too.
  777.     The regs[] and regused[] arrays may be overwritten by gen_code() as well
  778.     as parts of the list of ICs. However the list of ICs must still be a
  779.     valid list of ICs after gen_code() returned.
  780.  
  781. - void gen_ds(FILE *f, zlong size, struct Typ *t);
  782.  
  783.     Has to print output that generates size bytes of type t initialized
  784.     with proper 0.
  785.     t is a pointer to a struct Typ which contains the precise type of
  786.     the variable. On machines where every type can be initialized to 0
  787.     by setting all bits to zero the type does not matter.
  788.  
  789. - void gen_align(FILE *f, zlong align);
  790.  
  791.     Has to print output that ensures the following data to be aligned to
  792.     align bytes.
  793.  
  794. - void gen_var_head(FILE *f, struct Var *v);
  795.  
  796.     Has to print the head of a static or external variable v. This includes
  797.     the label and necessary informations for external linkage etc.
  798.  
  799.     Typically variables will be generated by a call to gen_align followed
  800.     by gen_var_head and (a series of) calls to gen_dc and/or gen_ds.
  801.  
  802. - void gen_dc(FILE *f, int t, struct const_list *p);
  803.  
  804.     Well..I'm too lazy at the moment to describe that...
  805.     Also arguments may still change in the future.
  806.  
  807.  
  808. Volker Barthelmann                                      volker@vb.franken.de
  809.  
  810.